box.schema.space.create() | Tarantool
Submodule box.space box.schema.space.create()

box.schema.space.create()

box.schema.space.create(space-name[, {space_opts}])
box.schema.create_space(space-name[, {space_opts}])

Create a space. You can use either syntax. For example, s = box.schema.space.create('tester') has the same effect as s = box.schema.create_space('tester').

There are three syntax variations for object references targeting space objects, for example box.schema.space.drop(space-id) drops a space. However, the common approach is to use functions attached to the space objects, for example space_object:drop().

After a space is created, usually the next step is to create an index for it, and then it is available for insert, select, and all the other box.space functions.

Parameters:
Return:

space object

Rtype:

userdata

object space_opts

Space options that include the space id, format, field count, constraints and foreign keys, and so on. These options are passed to the box.schema.space.create() method.

Note

These options are also passed to space_object:alter().

space_opts.if_not_exists

Create a space only if a space with the same name does not exist already. Otherwise, do nothing but do not cause an error.

Type: boolean
Default: false
space_opts.engine

A storage engine.

Type: string
Default: memtx
Possible values: memtx, vinyl
space_opts.id

A unique numeric identifier of the space: users can refer to spaces with this id instead of the name.

Type: number
Default: last space’s ID + 1
space_opts.field_count

A fixed count of fields. For example, if field_count=5, it is illegal to insert a tuple with fewer than or more than 5 fields.

Type: number
Default: 0 (not fixed)
space_opts.user

The name of the user who is considered to be the space’s owner for authorization purposes.

Type: string
Default: current user’s name
space_opts.format

Field names and types. See the illustrations of format clauses in the space_object:format() description and in the box.space._space example. Optional and usually not specified.

Type: table
Default: blank
space_opts.is_local

Space contents are replication-local: changes are stored in the write-ahead log of the local node but there is no replication.

Type: boolean
Default: false
space_opts.temporary

Space contents are temporary: changes are not stored in the write-ahead log and there is no replication.

Note

Vinyl does not support temporary spaces.

Type: boolean
Default: false
space_opts.is_sync

Any transaction doing a DML request on this space becomes synchronous.

Type: boolean
Default: false
space_opts.constraint

The constraints that space tuples must satisfy.

Type: table
Default: blank

Example:

-- Define a tuple constraint function --
box.schema.func.create('check_person', {
    language = 'LUA',
    is_deterministic = true,
    body = 'function(t, c) return (t.age >= 0 and #(t.name) > 3) end'
})

-- Create a space with a tuple constraint --
customers = box.schema.space.create('customers', {constraint = 'check_person'})
space_opts.foreign_key

The foreign keys for space fields.

Type: table
Default: blank

Example:

-- Create a space with a tuple foreign key --
box.schema.space.create("orders", {
    foreign_key = {
        space = 'customers',
        field = {customer_id = 'id', customer_name = 'name'}
    }
})

box.space.orders:format({
    {name = "id", type = "number"},
    {name = "customer_id" },
    {name = "customer_name"},
    {name = "price_total", type = "number"},
})

Saying box.cfg{read_only=true...} during configuration affects spaces differently depending on the options that were used during box.schema.space.create, as summarized by this chart:

Option Can be created? Can be written to? Is replicated? Is persistent?
(default) no no yes yes
temporary no yes no no
is_local no yes no yes

Example:

tarantool> s = box.schema.space.create('space55')
---
...
tarantool> s = box.schema.space.create('space55', {
         >   id = 555,
         >   temporary = false
         > })
---
- error: Space 'space55' already exists
...
tarantool> s = box.schema.space.create('space55', {
         >   if_not_exists = true
         > })
---
...
Found what you were looking for?
Feedback